\subsection{Upgrading OpenHPC Packages}  \label{appendix:upgrade}


As newer \OHPC{} releases are made available, users are encouraged to upgrade
their locally installed packages against the latest repository versions to
obtain access to bug fixes and newer component versions. This can be
accomplished with the underlying package manager as \OHPC{} packaging maintains
versioning state across releases. Also, package builds available from the
\OHPC{} repositories have ``\texttt{-ohpc}'' appended to their names so that
wild cards can be used as a simple way to obtain updates. The following general
procedure highlights a method for upgrading existing installations.
When upgrading from a minor release older than v\OHPCVerTree{}, you will first
need to update your local \OHPC{} repository configuration to point against the
v\OHPCVerTree{} release (or update your locally hosted mirror). Refer to
\S\ref{sec:enable_repo} for more details on enabling the latest
repository. In contrast, when upgrading between micro releases on the same
branch (e.g. from v\OHPCVerTree{} to \OHPCVerTree{}.2), there is no need to
adjust local package manager configurations when using the public repository as
rolling updates are pre-configured.
 
\begin{enumerate*}
\item (Optional) Ensure repo metadata is current (on head node and in chroot
  location(s)). Package managers will naturally do this on their own over time,
  but if you are wanting to access updates immediately after a new release,
  the following can be used to sync to the latest.

\begin{lstlisting}[language=bash,keywords={}]
[sms](*\#*)  (*\clean*)
[sms](*\#*)  (*\chrootclean*)
\end{lstlisting}

\item Upgrade master (SMS) node

\begin{lstlisting}[language=bash,keywords={}]
[sms](*\#*)  (*\upgrade*) "*-ohpc"

# Any new Base OS provided dependencies can be installed by
# updating the ohpc-base metapackage
[sms](*\#*)  (*\upgrade*) "ohpc-base"
\end{lstlisting}
  
\iftoggleverb{isWarewulf}
\begin{center}
\begin{tcolorbox}[]
\small
The version of \Warewulf{} included in \OHPC{} v1.3.6 added a new
architecture-specific package containing iPXE files. Upgraders will need to
install this package on the SMS node.
\begin{lstlisting}[language=bash,keywords={},literate={-}{-}1 {ARCH}{\arch{}}1]
[sms](*\#*)  (*\install*) warewulf-provision-server-ipxe-ARCH-ohpc
\end{lstlisting}
\end{tcolorbox}
\end{center}
\fi

\item Upgrade packages in compute image

\begin{lstlisting}[language=bash,keywords={}]
[sms](*\#*)  (*\chrootupgrade*) "*-ohpc"

# Any new compute-node Base OS provided dependencies can be installed by
# updating the ohpc-base-compute metapackage
[sms](*\#*)  (*\chrootupgrade*) "ohpc-base-compute"
\end{lstlisting}
  
\item Rebuild image(s)

\iftoggleverb{isWarewulf}
\begin{lstlisting}[language=bash,keywords={}]
[sms](*\#*) wwvnfs --chroot $CHROOT
\end{lstlisting}
\fi

\iftoggleverb{isxCAT}
\begin{lstlisting}[language=bash,keywords={},basicstyle=\fontencoding{T1}\fontsize{8.0}{10}\ttfamily,
    literate={-}{-}1 {BOSVER}{\baseos{}}1 {ARCH}{\arch{}}1]
[sms](*\#*) packimage BOSVER-x86_64-netboot-compute
\end{lstlisting}
\fi

\end{enumerate*}

\noindent In the case where packages were upgraded within the chroot compute image,
you will need to reboot the compute nodes when convenient to enable the
changes.

\subsubsection{New component variants}

As newer variants of key compiler/MPI stacks are released, \OHPC{} will
periodically add toolchains enabling the latest variant. To stay consistent
throughout the build hierarchy, minimize recompilation requirements for existing
binaries, and allow for multiple variants to coexist, unique delimiters are
used to distinguish RPM package names and module hierarchy.

In the case of a fresh install, \OHPC{} recipes default to installation of the
latest toolchains available in a given release branch. However, if upgrading a
previously installed system, administrators can {\em opt-in} to enable new
variants as they become available. To illustrate this point, consider the
previous \OHPC{} 1.3.5 release as an example which contained GCC 7.3.0
along with runtimes and libraries compiled with this toolchain.  In the case
where an admin would like to enable the newer {``gnu8''} toolchain,
installation of these additions is simplified with the use of \OHPC{}'s
meta-packages (see Table~\ref{table:groups} in Appendix
\ref{appendix:manifest}).  The following example illustrates adding the
complete ``gnu8'' toolchain.  Note that we leverage the convenience
meta-packages containing MPI-dependent builds, and we also update the
modules environment to make it the default.

\begin{lstlisting}[language=bash,keywords={}]
# Install GCC 8.x-compiled meta-packages with dependencies
[sms](*\#*)  (*\install*) ohpc-gnu8-perf-tools \
                         ohpc-gnu8-io-libs \
                         ohpc-gnu8-python-libs \
                         ohpc-gnu8-runtimes \
                         ohpc-gnu8-serial \
                         ohpc-gnu8-parallel-libs

# Update default environment
[sms](*\#*) (*\remove*) lmod-defaults-gnu7-openmpi3-ohpc
[sms](*\#*) (*\install*) lmod-defaults-gnu8-openmpi3-ohpc

\end{lstlisting}

